IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3/SCSL/zpsldlt.z/zpsldlt

Text File | 2002-10-03 | 44.4 KB | 595 lines

ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))                                                        ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))



NNNNAAAAMMMMEEEE
     ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____DDDDeeeessssttttrrrrooooyyyy, ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____EEEExxxxttttrrrraaaaccccttttPPPPeeeerrrrmmmm, ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrr, ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrrOOOOOOOOCCCC,
     ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOOOOOCCCCLLLLiiiimmmmiiiitttt, ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOOOOOCCCCPPPPaaaatttthhhh, ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOrrrrddddeeeerrrriiiinnnngggg, ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPrrrreeeepppprrrroooocccceeeessssssss,
     ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPrrrreeeepppprrrroooocccceeeessssssssZZZZ, ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeee, ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeeeMMMM, ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSttttoooorrrraaaaggggeeee -
     Parallel sparse symmetric solver for linear systems of complex equations

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     Fortran synopsis:

          SSSSUUUUBBBBRRRROOOOUUUUTTTTIIIINNNNEEEE ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____DDDDEEEESSSSTTTTRRRROOOOYYYY ((((_t_o_k_e_n))))
          IIIINNNNTTTTEEEEGGGGEEEERRRR _t_o_k_e_n

          SSSSUUUUBBBBRRRROOOOUUUUTTTTIIIINNNNEEEE ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____EEEEXXXXTTTTRRRRAAAACCCCTTTTPPPPEEEERRRRMMMM ((((_t_o_k_e_n,,,, _p_e_r_m))))
          IIIINNNNTTTTEEEEGGGGEEEERRRR _t_o_k_e_n,,,, _p_e_r_m(*)

          SSSSUUUUBBBBRRRROOOOUUUUTTTTIIIINNNNEEEE ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFAAAACCCCTTTTOOOORRRR ((((_t_o_k_e_n,,,, _n,,,, _p_o_i_n_t_e_r_s,,,, _i_n_d_i_c_e_s,,,, _v_a_l_u_e_s))))
          IIIINNNNTTTTEEEEGGGGEEEERRRR _t_o_k_e_n,,,, _n,,,, _p_o_i_n_t_e_r_s(*),,,, _i_n_d_i_c_e_s(*)
          DDDDOOOOUUUUBBBBLLLLEEEE CCCCOOOOMMMMPPPPLLLLEEEEXXXX _v_a_l_u_e_s(*)

          SSSSUUUUBBBBRRRROOOOUUUUTTTTIIIINNNNEEEE ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFAAAACCCCTTTTOOOORRRROOOOOOOOCCCC ((((_t_o_k_e_n,,,, _n,,,, _p_o_i_n_t_e_r_s,,,, _i_n_d_i_c_e_s,,,, _v_a_l_u_e_s))))
          IIIINNNNTTTTEEEEGGGGEEEERRRR _t_o_k_e_n,,,, _n,,,, _p_o_i_n_t_e_r_s(*),,,, _i_n_d_i_c_e_s(*)
          DDDDOOOOUUUUBBBBLLLLEEEE CCCCOOOOMMMMPPPPLLLLEEEEXXXX _v_a_l_u_e_s(*)

          SSSSUUUUBBBBRRRROOOOUUUUTTTTIIIINNNNEEEE ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOOOOOCCCCLLLLIIIIMMMMIIIITTTT ((((_t_o_k_e_n,,,, _o_o_c_l_i_m_i_t))))
          IIIINNNNTTTTEEEEGGGGEEEERRRR _t_o_k_e_n
          DDDDOOOOUUUUBBBBLLLLEEEE PPPPRRRREEEECCCCIIIISSSSIIIIOOOONNNN _o_o_c_l_i_m_i_t

          SSSSUUUUBBBBRRRROOOOUUUUTTTTIIIINNNNEEEE ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOOOOOCCCCPPPPAAAATTTTHHHH ((((_t_o_k_e_n,,,, _o_o_c_p_a_t_h))))
          IIIINNNNTTTTEEEEGGGGEEEERRRR _t_o_k_e_n
          CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR _o_o_c_p_a_t_h(*)

          SSSSUUUUBBBBRRRROOOOUUUUTTTTIIIINNNNEEEE ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOORRRRDDDDEEEERRRRIIIINNNNGGGG ((((_t_o_k_e_n,,,, _m_e_t_h_o_d))))
          IIIINNNNTTTTEEEEGGGGEEEERRRR _t_o_k_e_n,,,, _m_e_t_h_o_d

          SSSSUUUUBBBBRRRROOOOUUUUTTTTIIIINNNNEEEE ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPRRRREEEEPPPPRRRROOOOCCCCEEEESSSSSSSS ((((_t_o_k_e_n,,,, _n,,,, _p_o_i_n_t_e_r_s,,,, _i_n_d_i_c_e_s,,,,
          _n_o_n__z_e_r_o_s,,,, _o_p_s))))
          IIIINNNNTTTTEEEEGGGGEEEERRRR _t_o_k_e_n,,,, _n,,,, _p_o_i_n_t_e_r_s(*),,,, _i_n_d_i_c_e_s(*)
          IIIINNNNTTTTEEEEGGGGEEEERRRR****8888 _n_o_n__z_e_r_o_s
          DDDDOOOOUUUUBBBBLLLLEEEE PPPPRRRREEEECCCCIIIISSSSIIIIOOOONNNN _o_p_s

          SSSSUUUUBBBBRRRROOOOUUUUTTTTIIIINNNNEEEE ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPRRRREEEEPPPPRRRROOOOCCCCEEEESSSSSSSSZZZZ ((((_t_o_k_e_n,,,, _n,,,, _p_o_i_n_t_e_r_s,,,, _i_n_d_i_c_e_s,,,, _m_a_s_k,,,,
          _n_o_n__z_e_r_o_s,,,, _o_p_s))))
          IIIINNNNTTTTEEEEGGGGEEEERRRR _t_o_k_e_n,,,, _n,,,, _p_o_i_n_t_e_r_s(*),,,, _i_n_d_i_c_e_s(*),,,, _m_a_s_k(*)
          IIIINNNNTTTTEEEEGGGGEEEERRRR****8888 _n_o_n__z_e_r_o_s
          DDDDOOOOUUUUBBBBLLLLEEEE PPPPRRRREEEECCCCIIIISSSSIIIIOOOONNNN _o_p_s

          SSSSUUUUBBBBRRRROOOOUUUUTTTTIIIINNNNEEEE ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSOOOOLLLLVVVVEEEE ((((_t_o_k_e_n,,,, _x,,,, _b))))
          IIIINNNNTTTTEEEEGGGGEEEERRRR _t_o_k_e_n
          DDDDOOOOUUUUBBBBLLLLEEEE CCCCOOOOMMMMPPPPLLLLEEEEXXXX _x(*),,,, _b(*)






                                                                        PPPPaaaaggggeeee 1111






ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))                                                        ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))



          SSSSUUUUBBBBRRRROOOOUUUUTTTTIIIINNNNEEEE ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSOOOOLLLLVVVVEEEEMMMM ((((_t_o_k_e_n,,,, _X,,,, _l_d_x,,,, _B,,,, _l_d_b,,,, _n_r_h_s))))
          IIIINNNNTTTTEEEEGGGGEEEERRRR _t_o_k_e_n,,,, _l_d_x,,,, _l_d_b,,,, _n_r_h_s
          DDDDOOOOUUUUBBBBLLLLEEEE CCCCOOOOMMMMPPPPLLLLEEEEXXXX _X(*),,,, _B(*)

          DDDDOOOOUUUUBBBBLLLLEEEE PPPPRRRREEEECCCCIIIISSSSIIIIOOOONNNN FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSTTTTOOOORRRRAAAAGGGGEEEE((((_t_o_k_e_n))))
          IIIINNNNTTTTEEEEGGGGEEEERRRR _t_o_k_e_n

     C/C++ synopsis:

          ####iiiinnnncccclllluuuuddddeeee <<<<ssssccccssssllll____ssssppppaaaarrrrsssseeee....hhhh>>>>

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____DDDDeeeessssttttrrrrooooyyyy ((((iiiinnnntttt _t_o_k_e_n))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____EEEExxxxttttrrrraaaaccccttttPPPPeeeerrrrmmmm ((((iiiinnnntttt _t_o_k_e_n,,,, iiiinnnntttt _p_e_r_m[[[[]]]]))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrr ((((iiiinnnntttt _t_o_k_e_n,,,, iiiinnnntttt _n,,,, iiiinnnntttt _p_o_i_n_t_e_r_s[[[[]]]],,,, iiiinnnntttt
          _i_n_d_i_c_e_s[[[[]]]],,,, ssssccccssssllll____zzzzoooommmmpppplllleeeexxxx _v_a_l_u_e_s[[[[]]]]))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrrOOOOOOOOCCCC ((((iiiinnnntttt _t_o_k_e_n,,,, iiiinnnntttt _n,,,, iiiinnnntttt _p_o_i_n_t_e_r_s[[[[]]]],,,, iiiinnnntttt
          _i_n_d_i_c_e_s[[[[]]]],,,, ssssccccssssllll____zzzzoooommmmpppplllleeeexxxx _v_a_l_u_e_s[[[[]]]]))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOOOOOCCCCLLLLiiiimmmmiiiitttt ((((iiiinnnntttt _t_o_k_e_n,,,, ddddoooouuuubbbblllleeee _o_o_c_l_i_m_i_t))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOOOOOCCCCPPPPaaaatttthhhh ((((iiiinnnntttt _t_o_k_e_n,,,, cccchhhhaaaarrrr _o_o_c_p_a_t_h[[[[]]]]))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOrrrrddddeeeerrrriiiinnnngggg ((((iiiinnnntttt _t_o_k_e_n,,,, iiiinnnntttt _m_e_t_h_o_d))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPrrrreeeepppprrrroooocccceeeessssssss ((((iiiinnnntttt _t_o_k_e_n,,,, iiiinnnntttt _n,,,, iiiinnnntttt _p_o_i_n_t_e_r_s[[[[]]]],,,, iiiinnnntttt
          _i_n_d_i_c_e_s[[[[]]]],,,, lllloooonnnngggg lllloooonnnngggg *_n_o_n__z_e_r_o_s,,,, ddddoooouuuubbbblllleeee *_o_p_s))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPrrrreeeepppprrrroooocccceeeessssssssZZZZ ((((iiiinnnntttt _t_o_k_e_n,,,, iiiinnnntttt _n,,,, iiiinnnntttt _p_o_i_n_t_e_r_s[[[[]]]],,,, iiiinnnntttt
          _i_n_d_i_c_e_s[[[[]]]],,,, iiiinnnntttt _m_a_s_k[[[[]]]],,,, lllloooonnnngggg lllloooonnnngggg *_n_o_n__z_e_r_o_s,,,, ddddoooouuuubbbblllleeee *_o_p_s))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeee ((((iiiinnnntttt _t_o_k_e_n,,,, ssssccccssssllll____zzzzoooommmmpppplllleeeexxxx _x[[[[]]]],,,, ssssccccssssllll____zzzzoooommmmpppplllleeeexxxx _b[[[[]]]]))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeeeMMMM ((((iiiinnnntttt _t_o_k_e_n,,,, ssssccccssssllll____zzzzoooommmmpppplllleeeexxxx _X[[[[]]]],,,, iiiinnnntttt _l_d_x,,,,
          ssssccccssssllll____zzzzoooommmmpppplllleeeexxxx _B[[[[]]]],,,, iiiinnnntttt _l_d_b,,,, iiiinnnntttt _n_r_h_s))));;;;

          ddddoooouuuubbbblllleeee ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSttttoooorrrraaaaggggeeee ((((iiiinnnntttt _t_o_k_e_n))));;;;

     C++ STL synopsis:

          ####iiiinnnncccclllluuuuddddeeee <<<<ccccoooommmmpppplllleeeexxxx....hhhh>>>>
          ####iiiinnnncccclllluuuuddddeeee <<<<ssssccccssssllll____ssssppppaaaarrrrsssseeee....hhhh>>>>

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____DDDDeeeessssttttrrrrooooyyyy ((((iiiinnnntttt _t_o_k_e_n))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____EEEExxxxttttrrrraaaaccccttttPPPPeeeerrrrmmmm ((((iiiinnnntttt _t_o_k_e_n,,,, iiiinnnntttt _p_e_r_m[[[[]]]]))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrr ((((iiiinnnntttt _t_o_k_e_n,,,, iiiinnnntttt _n,,,, iiiinnnntttt _p_o_i_n_t_e_r_s[[[[]]]],,,, iiiinnnntttt
          _i_n_d_i_c_e_s[[[[]]]],,,, ccccoooommmmpppplllleeeexxxx<<<<ddddoooouuuubbbblllleeee>>>> _v_a_l_u_e_s[[[[]]]]))));;;;




                                                                        PPPPaaaaggggeeee 2222






ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))                                                        ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))



          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrrOOOOOOOOCCCC ((((iiiinnnntttt _t_o_k_e_n,,,, iiiinnnntttt _n,,,, iiiinnnntttt _p_o_i_n_t_e_r_s[[[[]]]],,,, iiiinnnntttt
          _i_n_d_i_c_e_s[[[[]]]],,,, ccccoooommmmpppplllleeeexxxx<<<<ddddoooouuuubbbblllleeee>>>> _v_a_l_u_e_s[[[[]]]]))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOOOOOCCCCLLLLiiiimmmmiiiitttt ((((iiiinnnntttt _t_o_k_e_n,,,, ddddoooouuuubbbblllleeee _o_o_c_l_i_m_i_t))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOOOOOCCCCPPPPaaaatttthhhh ((((iiiinnnntttt _t_o_k_e_n,,,, cccchhhhaaaarrrr _o_o_c_p_a_t_h[[[[]]]]))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOrrrrddddeeeerrrriiiinnnngggg ((((iiiinnnntttt _t_o_k_e_n,,,, iiiinnnntttt _m_e_t_h_o_d))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPrrrreeeepppprrrroooocccceeeessssssss ((((iiiinnnntttt _t_o_k_e_n,,,, iiiinnnntttt _n,,,, iiiinnnntttt _p_o_i_n_t_e_r_s[[[[]]]],,,, iiiinnnntttt
          _i_n_d_i_c_e_s[[[[]]]],,,, lllloooonnnngggg lllloooonnnngggg *_n_o_n__z_e_r_o_s,,,, ddddoooouuuubbbblllleeee *_o_p_s))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPrrrreeeepppprrrroooocccceeeessssssssZZZZ ((((iiiinnnntttt _t_o_k_e_n,,,, iiiinnnntttt _n,,,, iiiinnnntttt _p_o_i_n_t_e_r_s[[[[]]]],,,, iiiinnnntttt
          _i_n_d_i_c_e_s[[[[]]]],,,, iiiinnnntttt _m_a_s_k[[[[]]]],,,, lllloooonnnngggg lllloooonnnngggg *_n_o_n__z_e_r_o_s,,,, ddddoooouuuubbbblllleeee *_o_p_s))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeee ((((iiiinnnntttt _t_o_k_e_n,,,, ccccoooommmmpppplllleeeexxxx<<<<ddddoooouuuubbbblllleeee>>>> _x[[[[]]]],,,, ccccoooommmmpppplllleeeexxxx<<<<ddddoooouuuubbbblllleeee>>>>
          _b[[[[]]]]))));;;;

          vvvvooooiiiidddd ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeeeMMMM ((((iiiinnnntttt _t_o_k_e_n,,,, ccccoooommmmpppplllleeeexxxx<<<<ddddoooouuuubbbblllleeee>>>> _X[[[[]]]],,,, iiiinnnntttt _l_d_x,,,,
          ccccoooommmmpppplllleeeexxxx<<<<ddddoooouuuubbbblllleeee>>>> _B[[[[]]]],,,, iiiinnnntttt _l_d_b,,,, iiiinnnntttt _n_r_h_s))));;;;

          ddddoooouuuubbbblllleeee ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSttttoooorrrraaaaggggeeee ((((iiiinnnntttt _t_o_k_e_n))));;;;

IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
     These routines are part of the SCSL Scientific Library and can be loaded
     using either the ----llllssssccccssss or the ----llllssssccccssss____mmmmpppp option.  The ----llllssssccccssss____mmmmpppp option
     directs the linker to use the multi-processor version of the library.

     When linking to SCSL with ----llllssssccccssss or ----llllssssccccssss____mmmmpppp, the default integer size is
     4 bytes (32 bits). Another version of SCSL is available in which integers
     are 8 bytes (64 bits). This version allows the user access to larger
     memory sizes and helps when porting legacy Cray codes.  It can be loaded
     by using the ----llllssssccccssss____iiii8888 option or the ----llllssssccccssss____iiii8888____mmmmpppp option.  A program may
     use only one of the two versions; 4-byte integer and 8-byte integer
     library calls cannot be mixed.

     The C and C++ prototypes shown above are appropriate for the 4-byte
     integer version of SCSL. When using the 8-byte integer version, the
     variables of type iiiinnnntttt become lllloooonnnngggg lllloooonnnngggg and the <<<<ssssccccssssllll____ssssppppaaaarrrrsssseeee____iiii8888....hhhh>>>> header
     file should be included.

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     ZZZZPPPPSSSSLLLLDDDDLLLLTTTT solves sparse symmetric linear systems of the form _A_x = _b where _A
     is a complex _n-by-_n symmetric input matrix, _b is a complex input vector
     of length _n, and _x is a complex unknown vector of length _n.  Hermitian
     symmetric matrices are not supported at this time; to handle structures
     of this type, use a full matrix representation as input to ZZZZPPPPSSSSLLLLDDDDLLLLTTTT(3S).

     ZZZZPPPPSSSSLLLLDDDDLLLLTTTT uses a direct method. _A is factored into the following form:






                                                                        PPPPaaaaggggeeee 3333






ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))                                                        ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))



          _A = _L _D _L_T

     where _L is a lower triangular matrix with unit diagonal and _D is a
     diagonal matrix.

     Note that NO PIVOTING FOR STABILITY is performed during factorization.

     The ZZZZPPPPSSSSLLLLDDDDLLLLTTTT library contains five main routines.

     *   ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOrrrrddddeeeerrrriiiinnnngggg(((()))) allows the user to select one of five possible
         reordering methods to be used in the matrix preprocessing phase.

     *   ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPrrrreeeepppprrrroooocccceeeessssssss(((()))) performs preprocessing operations on the
         structure of _A (heuristic reordering to reduce fill in _L, symbolic
         factorization, etc.).

     *   ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrr(((()))) factors the matrix _A into _L and _D, using the
         previously computed preprocessing data.

     *   ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeee(((()))) solves for a vector _x, given an input vector _b.

     *   ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____DDDDeeeessssttttrrrrooooyyyy(((()))) frees all storage associated with the matrix _A
         (including _L, _D, and various data structures computed during
         preprocessing).

     The user can call ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrr(((()))) several times after a single call to
     ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPrrrreeeepppprrrroooocccceeeessssssss(((()))) to factor multiple matrices with identical non-zero
     structures but different values.  Similarly, the user can call
     ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeee(((()))) several times after a single call to ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrr(((()))) to
     solve for multiple right-hand-sides.  Also, the user can call
     ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeeeMMMM(((()))) to solve for multiple right-hand-sides all stored in a
     single array.

   SSSSppppaaaarrrrsssseeee MMMMaaaattttrrrriiiixxxx FFFFoooorrrrmmmmaaaatttt
     Sparse matrix _A must be input to ZZZZPPPPSSSSLLLLDDDDLLLLTTTT in Harwell-Boeing format (also
     known as Compressed Column Storage format).

     The matrix is held in three arrays: _p_o_i_n_t_e_r_s, _i_n_d_i_c_e_s, and _v_a_l_u_e_s.  The
     _i_n_d_i_c_e_s array contains the row indices of the non-zeros in _A. The _v_a_l_u_e_s
     array holds the corresponding non-zero values. The _p_o_i_n_t_e_r_s array
     contains the index in _i_n_d_i_c_e_s for the first non-zero in each column of _A.
     Thus, the row indices for the non-zeros in column _i can be found in
     locations _i_n_d_i_c_e_s[[[[_p_o_i_n_t_e_r_s[[[[_i]]]]]]]] through _i_n_d_i_c_e_s[[[[_p_o_i_n_t_e_r_s[[[[_i+1]]]]-1]]]]. The
     corresponding values can be found in location _v_a_l_u_e_s[[[[_p_o_i_n_t_e_r_s[[[[_i]]]]]]]] through
     _v_a_l_u_e_s[[[[_p_o_i_n_t_e_r_s[[[[_i+1]]]]-1]]]].

     For a symmetric matrix _A, the user must input either the lower or upper
     triangle of _A, but not both.  Non-zeroes within a column of _A can be
     stored in any order.






                                                                        PPPPaaaaggggeeee 4444






ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))                                                        ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))



     In the following example, the symmetric matrix

     (1.0,2.0)
     (0.0,0.0) (3.0,6.0)
     (2.0,4.0) (0.0,0.0) (5.0,10.0)
     (0.0,0.0) (4.0,8.0) (0.0, 0.0) (6.0,12.0)


     would be represented in FORTRAN as follows:

      INTEGER pointers(5), indices(6), i
      DOUBLE COMPLEX values(6)
      DATA (pointers(i), i = 1, 5) / 1, 3, 5, 6, 7 /
      DATA (indices(i),  i = 1, 6) / 1, 3, 2, 4, 3, 4 /
      DATA (values(i),   i = 1, 6) / (1.0,2.0), (2.0,4.0), (3.0,6.0),
     &                               (4.0,8.0), (5.0,10.0), (6.0,12.0) /


     Zero-based indexing is used in C, so the _p_o_i_n_t_e_r_s and _i_n_d_i_c_e_s arrays
     would instead contain the following:

     #include <scsl_sparse.h>
     int pointers[]        = {0, 2, 4, 5, 6};
     int indices[]         = {0, 2, 1, 3, 2, 3};
     scsl_zomplex values[] = {{1.0,2.0}, {2.0,4.0}, {3.0,6.0},
                              {4.0,8.0}, {5.0,10.0}, {6.0,12.0}};


   OOOOrrrrddddeeeerrrriiiinnnngggg MMMMeeeetttthhhhooooddddssss
     The ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOrrrrddddeeeerrrriiiinnnngggg((((_t_o_k_e_n,,,, _m_e_t_h_o_d)))) routine allows the user to change the
     ordering method used to pre-order the matrix before factorization.  This
     routine must be called before calling ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPrrrreeeepppprrrroooocccceeeessssssss(((()))). Five options
     are currently available for the method parameter:

     *   Method 0 performs no pre-ordering

     *   Method 1 performs Approximate Minimum Fill ordering

     *   Method 2 performs a single nested dissection ordering (default).
         This method is often called "Extreme matrix ordering".

     *   Method 3 performs multiple nested dissection orderings (in parallel)

     *   Method 4 performs multiple nested dissection (the same as in Method
         3), but it uses a feedback file to "learn" from the previous solves
         of the same matrix structure and it performs more orderings. The
         multiple nested dissection technique of Methods 3 and 4 is also
         referred to as "Extreme2 matrix ordering".

     Method 2 is significantly more expensive than Method 1, but it usually
     produces significantly better orderings.  Method 3 is especially
     effective on multi-processor systems.  It computes OOOOMMMMPPPP____NNNNUUUUMMMM____TTTTHHHHRRRREEEEAAAADDDDSSSS (where



                                                                        PPPPaaaaggggeeee 5555






ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))                                                        ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))



     OOOOMMMMPPPP____NNNNUUUUMMMM____TTTTHHHHRRRREEEEAAAADDDDSSSS is an environment variable indicating the number of
     processors to be used for parallel computation) matrix orderings using
     different starting points for the algorithm and uses the ordering that
     will lead to the fewest floating-point operations to factorize the
     matrix.

     Method 4 is useful only when the same non-zero structure is used for
     multiple solves.  Method 4 keeps a record in a "feedback" file of a
     signature for non-zero structures for a maximum of 200 matrices and of
     the starting point that was saved from a previous solve for that
     structure.  In the next Method 4 ordering for that non-zero structure,
     that best starting point and 2222 **** OOOOMMMMPPPP____NNNNUUUUMMMM____TTTTHHHHRRRREEEEAAAADDDDSSSS ---- 1111 new ones generate
     orderings.  The best ordering is used.  In this way, the quality of
     orderings stay the same or improve over time.

     Methods 3 and 4 typically take more time for the matrix preprocessing
     than the default.  However, on large systems or on repeated
     factorizations, significant overall speedups (1.1X to 2X) can be obtained
     compared to Method 2.

   EEEExxxxttttrrrraaaaccccttttiiiinnnngggg tttthhhheeee ppppeeeerrrrmmmmuuuuttttaaaattttiiiioooonnnn vvvveeeeccccttttoooorrrr
     Unless ordering Method 0 is used, ZZZZPPPPSSSSLLLLDDDDLLLLTTTT applies a symmetric permutation
     to matrix A before the factorization step; the resulting permuted matrix
     generally has significantly less fill-in than the original matrix.  The
     user can obtain the permutation matrix associated with a given token by
     calling ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____EEEExxxxttttrrrraaaaccccttttPPPPeeeerrrrmmmm((((_t_o_k_e_n,,,, _p_e_r_m)))). The permutation is returned as
     an integer array of length _n, with 1111 <<<<==== ppppeeeerrrrmmmm((((iiii)))) <<<<==== nnnn (0000 <<<<==== ppppeeeerrrrmmmm[[[[iiii]]]] <<<< nnnn
     for C code).

     A value of _k for _p_e_r_m(_i) implies that node _k in the original ordering is
     node _i in the new ordering.

   MMMMaaaattttrrrriiiicccceeeessss wwwwiiiitttthhhh zzzzeeeerrrroooossss oooonnnn tttthhhheeee ddddiiiiaaaaggggoooonnnnaaaallll
     As noted above, no pivoting is done for stability during factorization;
     when zero or near-zero pivots are encountered, ZZZZPPPPSSSSLLLLDDDDLLLLTTTT usually fails. In
     these cases, it may be possible to use ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPrrrreeeepppprrrroooocccceeeessssssssZZZZ(((()))) to obtain a
     slightly different, but stable, ordering.  The user provides an
     additional integer array, _m_a_s_k, as an argument to ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPrrrreeeepppprrrroooocccceeeessssssssZZZZ(((()))).
     If _m_a_s_k(_i)====0000, then ZZZZPPPPSSSSLLLLDDDDLLLLTTTT will attempt to maximize the diagonal element
     ||||AAAAiiiiiiii||||.

   MMMMeeeemmmmoooorrrryyyy uuuussssaaaaggggeeee
     The returned value of ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSttttoooorrrraaaaggggeeee(((()))) is an estimate of the amount of
     storage required (in millions of bytes) by the solver's data structures
     for a given matrix system.

   OOOOuuuutttt----ooooffff----ccccoooorrrreeee FFFFaaaaccccttttoooorrrriiiizzzzaaaattttiiiioooonnnn
     The storage associated with the factor can be managed in two ways.  The
     ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrr(((()))) routine allocates memory for the factor and manages it
     internally, releasing it only when ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____DDDDeeeessssttttrrrrooooyyyy(((()))) is called.  The
     alternative is to do out-of-core factorization by calling
     ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrrOOOOOOOOCCCC(((()))). This routine uses a small amount of in-core memory,



                                                                        PPPPaaaaggggeeee 6666






ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))                                                        ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))



     placing the remainder of the factor matrix on disk as it is computed.
     The user can call ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOOOOOCCCCPPPPaaaatttthhhh(((()))) to indicate the directory in which
     the factor file should be written, and ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____OOOOOOOOCCCCLLLLiiiimmmmiiiitttt(((()))) to indicate how
     much memory to use to hold portions of the factor matrix in-core.  More
     in-core memory generally leads to less disk I/O and higher performance
     during the factorization.  The only required change is to move from in-
     core factorization to out-of-core factorization is the change from
     ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrr(((()))) to ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrrOOOOOOOOCCCC(((()))).  The other routines
     (ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeee(((()))), ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____DDDDeeeessssttttrrrrooooyyyy(((()))), etc.) handle out-of-core factors
     transparently.  Note that ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrrOOOOOOOOCCCC(((()))) and subsequent calls to
     ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeee(((()))) are not parallelized (but calls to ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeeeMMMM(((()))) are
     parallelized, as discussed below).

   MMMMuuuullllttttiiiipppplllleeee RRRRiiiigggghhhhtttt----HHHHaaaannnndddd----SSSSiiiiddddeeeessss
     ZZZZPPPPSSSSLLLLDDDDLLLLTTTT can solve for large numbers of right-hand-sides with one call to
     ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeeeMMMM(((()))).  It solves these right hand sides in parallel, with
     each processor solving up to four at a time for in-core systems and up to
     PPPPSSSSLLLLDDDDLLLLTTTT____OOOOOOOOCCCCBBBBLLLLKKKK at a time for out-of-core systems, where PPPPSSSSLLLLDDDDLLLLTTTT____OOOOOOOOCCCCBBBBLLLLKKKK is
     an environment variable whose default value is 1.

   IIIInnnn----ppppllllaaaacccceeee SSSSoooollllvvvveeeessss
     Both ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeee(((()))) and ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeeeMMMM(((()))) allow the solution vector(s) to
     overwrite the right-hand-side(s) when identical vectors or matrices are
     supplied to these routines.  For example,

      CALL ZPSLDLT_SOLVE(token, b, b)


     takes the right-hand-side input from _b and also returns the solution
     vector in _b.  When this option is used with ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeeeMMMM(((()))), the leading
     dimensions for the solution and right-hand-side matrices must agree.  The
     amount of memory actually saved by performing an in-place solve depends
     on the number of right-hand-sides used.  For a single right-hand-side,
     there are no net savings versus an out-of-place solve because a temporary
     copy of the input vector is made internally.  For multiple right-hand-
     sides the memory overhead decreases as the ratio of right-hand-sides to
     processors used increases.

   AAAArrrrgggguuuummmmeeeennnnttttssss
     These routines have the following arguments:

     _t_o_k_e_n     (input) ZZZZPPPPSSSSLLLLDDDDLLLLTTTT can handle multiple matrices simultaneously.
               The _t_o_k_e_n distinguishes between active matrices.  The _t_o_k_e_n
               passed to ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrr(((()))) must match the _t_o_k_e_n used in some
               previous call to ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPrrrreeeepppprrrroooocccceeeessssssss(((()))).  Similarly, the _t_o_k_e_n
               passed to ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeee(((()))) must match the _t_o_k_e_n used in some
               previous call to ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrr(((()))).  0000 <<<<==== _t_o_k_e_n <<<<==== 11119999....

     _m_e_t_h_o_d    (input) An integer specifying the ordering method used during
               preprocessing.  0000 <<<<==== _m_e_t_h_o_d <<<<==== 4444....





                                                                        PPPPaaaaggggeeee 7777






ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))                                                        ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))



     _n         (input) The number of rows and columns in the matrix _A.  _n >>>>====
               0000....

     _p_o_i_n_t_e_r_s, _i_n_d_i_c_e_s, _v_a_l_u_e_s
               (input) The _p_o_i_n_t_e_r_s and _i_n_d_i_c_e_s arrays store the non-zero
               structure of sparse input matrix _A in Harwell-Boeing or
               Compressed Sparse Column (CSC) format.

               The _p_o_i_n_t_e_r_s array stores _n+1 integers, where _p_o_i_n_t_e_r_s[[[[_i]]]] gives
               the index in _i_n_d_i_c_e_s of the first non-zero in column _i of _A.
               The _i_n_d_i_c_e_s array stores the row indices of the non-zeros in _A.
               The _v_a_l_u_e_s array stores the non-zero values in the matrix _A.

     _n_o_n__z_e_r_o_s (output) The number of non-zero values in _L.

     _o_p_s       (output) The number of floating-point operations required to
               factor _A.

     _m_a_s_k      (input) An integer array of length _n used in
               ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____PPPPrrrreeeepppprrrroooocccceeeessssssssZZZZ(((()))).  If _m_a_s_k(_i) ==== 0000, then node _i of matrix A
               is ordered after all of its neighbors in an attempt to avoid a
               zero pivot.

     _b         (input) The right-hand-side vector in a ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeee(((()))) call.

     _x         (output) The solution vector in a ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeee(((()))) call.

     _n_r_h_s      (input) The number of right-hand side vectors present in a
               ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeeeMMMM(((()))) call.

     _B         (input) The right-hand-side matrix in a ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeeeMMMM(((()))) call.
               Must be stored in column-major order.

     _l_d_b       (input) The leading dimension of matrix _B. _l_d_b >>>>==== _n.

     _X         (output) The solution matrix in a ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____SSSSoooollllvvvveeeeMMMM(((()))) call. Must
               be stored in column-major order.

     _l_d_x       (input) The leading dimension of matrix _X. _l_d_x >>>>==== _n.

     _o_o_c_p_a_t_h   (input) A character array/string with a path to the directory
               where the temporary out-of-core factor files should be stored.
               If this path is on a striped (or raid-0) file system, the
               performance of the out-of-core solves can be considerably
               improved.  The default path is ////uuuussssrrrr////ttttmmmmpppp.

     _o_o_c_l_i_m_i_t  (input) A double precision number indicating the number of
               Mbytes of random access memory that should be used for factor
               storage during a call to ZZZZPPPPSSSSLLLLDDDDLLLLTTTT____FFFFaaaaccccttttoooorrrrOOOOOOOOCCCC(((()))). Note that there
               are many other arrays used besides those directly used to store
               the factorization, so total RAM usage by the solve will exceed
               this number.  The default is 64 MB.



                                                                        PPPPaaaaggggeeee 8888






ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))                                                        ZZZZPPPPSSSSLLLLDDDDLLLLTTTT((((3333SSSS))))



     _p_e_r_m      (output) An integer array of length _n containing the
               permutation used to reorder matrix A.

EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT VVVVAAAARRRRIIIIAAAABBBBLLLLEEEESSSS
     Two environment variables can affect the operation of ordering methods 3
     and 4.  SSSSPPPPAAAARRRRSSSSEEEE____NNNNUUUUMMMM____OOOORRRRDDDDEEEERRRRSSSS can be used to change the number of orderings
     performed from the default of OOOOMMMMPPPP____NNNNUUUUMMMM____TTTTHHHHRRRREEEEAAAADDDDSSSS for Method 3 and
     (2*OOOOMMMMPPPP____NNNNUUUUMMMM____TTTTHHHHRRRREEEEAAAADDDDSSSS) for Method 4.  SSSSPPPPAAAARRRRSSSSEEEE____FFFFEEEEEEEEDDDDBBBBAAAACCCCKKKK____FFFFIIIILLLLEEEE can be set to the
     path and file name where the feedback information will be kept;
     otherwise, the default feedback file is $$$$HHHHOOOOMMMMEEEE////....ssssppppaaaarrrrsssseeeeFFFFeeeeeeeeddddbbbbaaaacccckkkk.  This file
     will be less than 5K bytes.

     The environment variable OOOOMMMMPPPP____NNNNUUUUMMMM____TTTTHHHHRRRREEEEAAAADDDDSSSS determines the number of
     processors that are used for the numerical factorization and solve
     phases.  Out-of-core solves can be performed in groups of PPPPSSSSLLLLDDDDLLLLTTTT____OOOOOOOOCCCCBBBBLLLLKKKK
     right-hand-sides per processor.  Setting the environment variable
     PPPPSSSSLLLLDDDDLLLLTTTT____VVVVEEEERRRRBBBBOOOOSSSSEEEE causes ZZZZPPPPSSSSLLLLDDDDLLLLTTTT to output information about the
     factorization.

NNNNOOOOTTTTEEEESSSS
     These routines are optimized and parallelized for the SGI R8000 and
     R1x000 platforms.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     IIIINNNNTTTTRRRROOOO____SSSSCCCCSSSSLLLL(3S), IIIINNNNTTTTRRRROOOO____SSSSOOOOLLLLVVVVEEEERRRRSSSS(3S), ZZZZPPPPSSSSLLLLDDDDUUUU(3S), DDDDPPPPSSSSLLLLDDDDLLLLTTTT(3S), DDDDPPPPSSSSLLLLDDDDUUUU(3S)



























                                                                        PPPPaaaaggggeeee 9999